﻿#region Disclaimer/Info
///////////////////////////////////////////////////////////////////////////////////////////////////
// MetaCollection
// 
// MetaCollection is a system to provide a standard structure, permissions and metadata service
// for content organization.
//
// This project is hosted at Google Code at http://code.google.com/p/metacollection/
//
// This project is licensed under the BSD license.  See the License.txt file for more information.
///////////////////////////////////////////////////////////////////////////////////////////////////
#endregion


using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.IO;
using MetaCollection.Framework.Model;
using MetaCollection.Framework.Security;

namespace MetaCollection.Framework
{
	/// <summary>
	/// The IRequestHandler interface specifies the methods used to register IRequestSinks
	/// or IProviders into the request process.  The interface also exposes a few query methods
	/// that will invoke requests on the collection.
	/// </summary>
	public interface IRequestHandler : IDisposable
	{
		/// <summary>
		/// Registers the specified sink for notifications of the events in eventTypes.
		/// </summary>
		/// <param name="sink">The sink.</param>
		/// <param name="eventTypes">The event types.</param>
		void Register(IRequestSink sink, RequestEventTypes eventTypes);
		/// <summary>
		/// Unregisters the specified sink of the events in eventTypes.
		/// </summary>
		/// <param name="sink">The sink.</param>
		/// <param name="eventTypes">The event types.</param>
		void Unregister(IRequestSink sink, RequestEventTypes eventTypes);
		/// <summary>
		/// Invokes a Resource Request on the collection.
		/// </summary>
		/// <param name="user">The MetaPrincipal that the request should be performed as</param>
		/// <param name="requestType">Type of the reqeust.</param>
		/// <param name="itemPath">The item path.</param>
		/// <param name="stream">An optional stream to read an item resource from when saving.</param>
		/// <returns>A stream for reading the ItemResource data in Get type requests, <c>null</c> in Resource
		/// Set type requests</returns>
		Stream ResourceRequest(MetaPrincipal user, RequestTypes requestType, Uri itemPath, params object[] requestData);
		/// <summary>
		/// Invokes an Item Request on the collection.
		/// </summary>
		/// <param name="user">The MetaPrincipal that the request should be performed as</param>
		/// <param name="requestType">Type of the request.</param>
		/// <param name="itemPath">The item path.</param>
		/// <param name="requestData">The request data.</param>
		/// <returns>For Get Type <paramref name="requestType"/> requests this method will return an enummerable list of items.
		/// In some cases this will be an empty list if no items can be found to match the request or in the 
		/// case of a Delete request there is no item to return.</returns>
		IEnumerable<IItemInstance> ItemRequest(MetaPrincipal user, RequestTypes requestType, Uri itemPath, params object[] requestData);
		/// <summary>
		/// Returns the Item Specification (Validation Model) associated with the item identified by
		/// the <paramref name="itemPath"/>.
		/// </summary>
		/// <param name="user">The MetaPrincipal that the request should be performed as</param>
		/// <param name="itemPath"></param>
		/// <returns>The Item Model Specification.</returns>
		IItemSpecification ItemSpecificationRequest(MetaPrincipal user, Uri itemPath);
	}
}
